这是「OpenClaw 教程课程」第 18 课。
前两课我们讲了多 Agent：第 16 课讲 sessions_spawn，第 17 课讲 subagents 管理。今天进入自动化里最常用的一块：Cron 定时任务。

图：Cron 让 OpenClaw 可以在指定时间或固定周期自动唤醒 Agent，执行提醒、摘要、检查、报告等任务。

很多人第一次理解 OpenClaw 的自动化，会自然想到一句话：

“能不能让它每天自动帮我做点事？”

比如：

• 每天早上 8 点发一份晨报
• 每晚总结今天的任务
• 每周一检查项目状态
• 20 分钟后提醒我看某个文档
• 每隔一段时间跑一次健康检查
• 定时打开网页、收集信息、发回结果

这些事情，不应该靠你每天手动发消息。

也不应该让 Agent 在对话里傻等一个 sleep 3600。

在 OpenClaw 里，这类“到点自动执行”的工作，应该交给 Cron。

这一课我们讲清楚：

OpenClaw 的 Cron 是什么，怎么用，适合什么，不适合什么，以及怎样避免自动任务变成打扰。

一、Cron 是什么？

Cron 是 OpenClaw Gateway 内置的调度器。

文档里一句话说得很清楚：

Cron is the Gateway’s built-in scheduler.

翻译成新手能理解的话：

Cron 是 Gateway 里的定时任务系统。

它负责：

• 保存任务定义
• 在指定时间触发任务
• 唤醒 Agent
• 记录运行历史
• 必要时把结果发回聊天渠道或 webhook

这里有一个重点：

Cron 运行在 Gateway 里，不运行在模型里。

这意味着，模型不会一直“记着时间”等到点。

真正负责看时间、触发任务的是 Gateway。

到点以后，Gateway 再把任务交给 Agent 执行。

二、为什么不能让 Agent 自己等？

新手容易有一个错误想法：

1

让 AI 等 20 分钟后提醒我。

听起来可以，但技术上不应该这样做。

因为如果让 Agent 自己等，会出现很多问题：

• 占着当前对话运行
• 浪费模型或工具资源
• Gateway 重启后可能丢状态
• 无法稳定管理多个提醒
• 不好查看任务列表和历史
• 不能像真正调度器一样处理失败、重试和投递

所以正确做法是：

未来某个时间再做的事，交给 Cron。

这和第 12 课 exec 里讲过的原则一致：

不要用 sleep 循环模拟定时任务。

OpenClaw 已经有 Cron，就应该让 Gateway 调度。

图：sleep 只是让一个过程傻等；Cron 是 Gateway 持久化管理的调度系统，更适合提醒、周期任务和后台自动化。

三、Cron 适合做哪些事？

Cron 适合“明确时间触发”的任务。

1）一次性提醒

比如：

1

20 分钟后提醒我检查文章封面图。

或者：

1

明天上午 10 点提醒我发布第 18 课。

这类任务适合 one-shot job。

2）周期性摘要

比如：

• 每天早上发晨报
• 每晚总结今日任务
• 每周一发项目周报
• 每月 1 号整理账单提醒

这类任务适合 recurring job。

3）定时健康检查

比如：

• 每小时检查 Gateway 状态
• 每天检查磁盘空间
• 每周检查日志里有没有错误

这类任务可以结合 exec 做只读检查。

4）定时内容生产

比如：

• 每天生成一个教程选题
• 每周整理一篇阅读摘要
• 定时生成频道更新草稿

这类任务适合用 isolated session，避免污染主对话。

5）自动化报告

比如：

• 每天早上总结某个目录变化
• 每周检查文章是否缺 front matter
• 每天汇总昨天的任务结果

Cron 很适合“定时触发 + Agent 整理 + 发回结果”。

四、Cron 不适合做哪些事？

Cron 不是万能自动化。

下面这些情况不适合直接用 Cron。

1）需要实时连续监听的事情

比如：

1

一有新消息就马上处理。

这种更像 webhook、事件触发或 channel 消息处理。

Cron 是按时间触发，不是实时事件监听。

2）需要高频秒级循环的任务

比如每 5 秒检查一次状态。

这不适合 Cron，也不适合 Agent。

应该用专门监控系统，或者降低频率。

3）需要用户现场确认的敏感操作

比如：

• 到点自动删除文件
• 到点自动发公开消息
• 到点自动改生产配置

这些高风险动作不应该直接自动执行。

更好的做法是：

到点生成计划或提醒，由用户确认后再执行。

4）模糊目标

比如：

1

每天帮我做点有用的事。

这太模糊。

Cron 任务应该目标明确。

例如：

1

每天 9 点总结昨天 articles 目录新增或修改的 Markdown 文件，输出 5 条以内。

这样才可控。

五、Cron 的三种 schedule 类型

OpenClaw 文档里列了三种 schedule 类型：

1）at：一次性任务

适合提醒。

比如：

1
2
3
4
5
6

openclaw cron add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now

这里 20m 就是 20 分钟后。

也可以用 ISO 时间，比如：

1

2026-02-01T16:00:00Z

2）every：固定间隔

适合每隔一段时间做一次。

比如每小时、每 6 小时。

这种任务要谨慎，不要频率太高。

3）cron：标准 cron 表达式

适合复杂周期。

比如每天 7 点：

1

0 7 * * *

每周一 9 点：

1

0 9 * * 1

Cron 表达式很强，但也容易写错。

新手刚开始可以优先用 --at 和简单 --cron。

图：OpenClaw Cron 支持一次性 at、固定间隔 every、标准 cron 表达式三类调度方式。

六、时区：一定要说清楚

时间任务最容易踩坑的是时区。

文档里提到：

没有 timezone 的 timestamp 会按 UTC 处理。

所以如果你想按本地时间执行，最好明确传 --tz。

比如北京时间：

1

--tz "Asia/Shanghai"

例如每天早上 8 点按北京时间跑：

1
2
3
4
5
6
7

openclaw cron add \
  --name "Morning brief" \
  --cron "0 8 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "整理今日晨报，输出 5 条以内。" \
  --announce

不要只写“明早 8 点”，却不说时区。

尤其是服务器在 UTC、用户在中国时，非常容易差 8 小时。

七、执行位置：main / isolated / current / session:id

Cron 触发后，需要决定任务跑在哪个 session 里。

OpenClaw 文档里列了几种 --session：

这部分非常关键。

因为不同 session 会影响：

• 是否继承上下文
• 是否污染主对话
• 是否适合长期积累
• 结果怎么投递

八、main session：适合提醒和系统事件

main 适合轻量提醒。

比如：

1
2
3
4
5
6
7

openclaw cron add \
  --name "Reminder" \
  --at "20m" \
  --session main \
  --system-event "Reminder: check the cron docs draft" \
  --wake now \
  --delete-after-run

它更像：

到点往主会话塞一个系统事件，然后唤醒 Agent。

适合：

• 提醒你做某事
• 让主会话知道某个时间到了
• 简单唤醒

但不适合复杂后台分析。

复杂任务更推荐 isolated。

九、isolated session：适合后台报告

isolated 是自动化里非常常用的模式。

它的意思是：

每次 cron run 都在一个独立的新 session 里运行。

这有几个好处：

• 不污染主对话
• 每次运行上下文清爽
• 适合生成报告
• 适合跑后台检查
• 出问题也更容易隔离

例如每天早上生成晨报：

1
2
3
4
5
6
7
8
9

openclaw cron add \
  --name "Morning brief" \
  --cron "0 8 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "请整理今日晨报，控制在 5 条以内。" \
  --announce \
  --channel telegram \
  --to "telegram:7995226813"

这里的重点是：

• --session isolated：独立运行
• --message：给 Agent 的任务
• --announce：完成后投递结果
• --channel / --to：指定投递渠道和目标

新手可以先把 isolated 理解成：

让 cron 自己开一个干净的小房间做任务，做完把结果发回来。

图：main 适合提醒，isolated 适合后台报告，current 适合绑定当前上下文，session:id 适合长期持久工作流。

十、current session：绑定创建时的当前会话

current 的意思是：

创建 cron 任务时，把它绑定到当前会话。

适合这些场景：

• 当前对话里已经有上下文
• 你希望后续提醒和这个上下文有关
• 不是全局主会话，而是某个具体频道、群、线程或 direct chat

例如你正在某个项目对话里讨论 bug。

你可以说：

1

明天上午提醒我继续看这个 bug。

这类任务就可能适合 current。

但如果任务不需要当前上下文，isolated 更干净。

十一、session:：适合长期积累上下文

session:<id> 是更进阶的用法。

它适合让某个定时任务长期在同一个命名 session 里积累上下文。

比如：

• daily-brief
• weekly-report
• health-check-history

这样每次运行都不是完全陌生的。

它可以基于前几次结果继续积累。

但也要注意：

长期 session 可能积累噪音，也可能让上下文越来越重。

所以对新手来说，默认还是 isolated 更稳。

十二、Delivery：结果怎么发回来？

Cron 任务执行完，结果要不要发回来、发到哪里，是 delivery 问题。

文档里提到三种模式：

新手先理解 announce 就够了。

announce

announce 表示任务完成后，把结果发回指定渠道。

例如：

1

--announce --channel telegram --to "telegram:7995226813"

如果你不想它主动发消息，可以用：

1

--no-deliver

这会关闭 runner fallback delivery。

但注意，isolated cron chat delivery 是 shared 的。

如果有可用聊天路由，Agent 自己仍可能使用 message 工具发送，具体要看任务和工具策略。

十三、Cron 会记录运行历史

Cron 不只是“到点跑一下”。

它还会记录任务和运行历史。

常用命令：

1
2
3

openclaw cron list
openclaw cron show <job-id>
openclaw cron runs --id <job-id>

分别用于：

• list：查看所有 cron jobs
• show：查看某个 job 详情
• runs：查看某个 job 的运行历史

这对排错很重要。

比如你发现晨报没发出来，不要先猜。

先看：

1
2
3

openclaw cron list
openclaw cron show <job-id>
openclaw cron runs --id <job-id>

确认它是没触发、触发失败、模型失败，还是投递失败。

十四、Cron 和 Background Tasks 的关系

第 16、17 课讲子 Agent 时，我们提到 background tasks。

Cron 也会创建 task 记录。

OpenClaw 文档里说：

All cron executions create background task records.

也就是说，每次 cron 执行，都会进入后台任务账本。

Background tasks 不是调度器。

它是记录：

• 什么任务跑过
• 是否 queued / running / succeeded / failed / timed_out / cancelled / lost
• 运行是否完成
• 是否投递成功

你可以理解成：

Cron 决定什么时候跑，Tasks 记录跑得怎么样。

图：Cron 是调度器，负责按时间触发；Background Tasks 是账本，负责记录后台执行状态和结果。

十五、失败、跳过和重试

Cron 任务不一定每次都成功。

可能出现：

• 模型不可用
• 本地 provider 没启动
• 工具被拒绝
• 任务超时
• 投递失败
• 网络问题

OpenClaw 对这些情况有一些保护。

文档里提到：

• recurring jobs 遇到连续错误会用指数退避
• skipped runs 和 execution errors 分开记录
• isolated cron 对本地 provider 会做轻量 preflight
• blocked command 不会被当成绿色成功
• timeout 会中止底层 agent run

新手不需要一次记住全部细节。

你先记住：

Cron 不只是定时触发，它还会记录成功、失败、跳过和超时。

排错时，先看 run history，而不是凭感觉猜。

十六、一个最小例子：20 分钟后提醒

假设你想 20 分钟后提醒自己检查文章。

可以这样：

1
2
3
4
5
6
7

openclaw cron add \
  --name "Check article" \
  --at "20m" \
  --session main \
  --system-event "Reminder: check lesson 18 draft." \
  --wake now \
  --delete-after-run

解释一下：

• --name：任务名
• --at "20m"：20 分钟后
• --session main：发到主会话
• --system-event：到点注入的系统事件
• --wake now：唤醒处理
• --delete-after-run：成功后删除一次性任务

这是最适合理解 Cron 的例子。

它不是让 Agent 睡 20 分钟。

而是 Gateway 保存一个定时任务，到点再唤醒。

十七、一个实用例子：每天晨报

假设你想每天早上 8 点收到一个晨报。

可以用 isolated job：

1
2
3
4
5
6
7
8
9

openclaw cron add \
  --name "Morning brief" \
  --cron "0 8 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "请生成今日晨报，控制在 5 条以内。优先总结重要事项、风险和下一步行动。不要输出长篇背景。" \
  --announce \
  --channel telegram \
  --to "telegram:7995226813"

这个例子里，最重要的是 --message 写得清楚。

定时任务不能太模糊。

不要写：

1

每天跟我说点东西。

要写：

1

控制在 5 条以内，优先总结重要事项、风险和下一步行动。

自动化任务越清楚，越不容易变成噪音。

十八、一个检查例子：每周检查文章格式

假设你维护一个文章目录。

可以每周检查一次：

1
2
3
4
5
6
7
8
9
10

openclaw cron add \
  --name "Weekly article check" \
  --cron "0 9 * * 1" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "请检查 articles 目录下最近一周修改的 Markdown 文件，确认是否包含 title、description、cover 和配图建议。只读检查，不要修改文件。输出异常列表和建议。" \
  --tools read,exec \
  --announce \
  --channel telegram \
  --to "telegram:7995226813"

这里有两个好习惯：

1）明确只读

1

只读检查，不要修改文件。

2）限制工具

1

--tools read,exec

这能减少不必要风险。

当然，具体工具是否可用还取决于你的工具策略配置。

十九、Cron 和 Heartbeat 有什么区别？

第 20 课会专门讲 Heartbeat。

这里先做一个最小区分。

Cron：到点做明确任务

比如：

• 每天 8 点发晨报
• 20 分钟后提醒
• 每周一检查文章

Cron 的特点是：

有明确时间或周期。

Heartbeat：保持 Agent 活跃和处理后台事件

Heartbeat 更像系统周期性检查和唤醒机制。

它适合保持 Agent 活跃，处理某些后台状态。

不是所有定时任务都应该塞进 Heartbeat。

新手先记住：

明确时间表用 Cron；保持活跃和后台节奏用 Heartbeat。

第 20 课我们会细讲。

二十、适合新手的 Cron 提问模板

下面这些句式可以直接复制。

1）一次性提醒

1

请帮我创建一个 20 分钟后的一次性提醒：提醒我检查第 18 课草稿。成功后自动删除任务。

2）每天晨报

1

请帮我创建一个每天北京时间早上 8 点的 isolated cron job，生成 5 条以内晨报，并发送到当前 Telegram 对话。

3）只读检查

1

请创建一个每周一北京时间 9 点的 isolated cron job，只读检查 articles 目录最近一周修改的 Markdown 文件，不要修改文件，只输出异常和建议。

4）不主动发消息

1

请创建 cron job，但不要主动投递结果，只保留运行记录供我之后查看。

5）排查 Cron

1

请帮我检查现有 cron job 列表、某个 job 的详情和最近运行历史，判断为什么没有发送结果。

6）避免打扰

1

这个 cron job 的输出请控制在 5 条以内；没有异常时只发送一句简短结果，不要长篇解释。

7）带时区

1

请按 Asia/Shanghai 时区创建任务，不要用 UTC 默认时间。

这些模板背后的重点是：

时间、会话、输出、投递、边界都要说清楚。

图：创建 Cron 任务时，要明确时间、时区、session、任务边界、输出长度和投递方式，避免自动任务变成噪音。

二十一、常见坑

坑 1：忘记时区

服务器常用 UTC。

用户想的是北京时间。

如果不写 --tz Asia/Shanghai，很容易错 8 小时。

坑 2：用 sleep 模拟定时任务

不要让 Agent 或 exec 等着未来时间。

未来任务用 Cron。

坑 3：任务描述太模糊

比如：

1

每天帮我总结一下。

总结什么？从哪里总结？发多长？发到哪里？

都不清楚。

坑 4：自动任务输出太长

定时任务如果每天发长篇，很快会变成噪音。

建议：

默认短输出，有异常再展开。

坑 5：让 Cron 自动做高风险写操作

比如自动删除、自动发布、自动改配置。

更安全的方式是：

Cron 到点生成计划或提醒，由人确认后执行。

坑 6：不知道跑在哪个 session

main、isolated、current、session:<id> 差别很大。

不确定时，后台报告优先 isolated。

坑 7：没看运行历史就猜问题

Cron 没按预期工作时，先看：

1
2
3

openclaw cron list
openclaw cron show <job-id>
openclaw cron runs --id <job-id>

不要凭感觉改配置。

二十二、Cron 的安全原则

我建议记住这 6 条。

1. 未来任务用 Cron，不用 sleep。
2. 时间一定写清楚，尤其是时区。
3. 后台报告优先 isolated。
4. 自动输出要短，异常再展开。
5. 高风险动作只提醒，不自动执行。
6. 排错先看 job 和 run history。

这 6 条能避免大多数 Cron 使用问题。

二十三、这一课最值得记住的一句话

如果今天只记一句话，我建议你记这句：

Cron 不是让 AI 等时间，而是让 Gateway 到点唤醒 AI。

再补一句使用原则：

明确时间、明确任务、明确投递，自动化才不会变成打扰。

二十四、总结

今天这节课，我们讲清楚了 OpenClaw 的 Cron 定时任务：

1. Cron 是 Gateway 内置的调度器。
2. Cron 运行在 Gateway，不运行在模型里。
3. 未来某个时间再做的事，应该交给 Cron，而不是 sleep。
4. Cron 支持 at、every、cron 三类 schedule。
5. 没有 timezone 的时间默认按 UTC，建议明确 --tz。
6. main 适合提醒，isolated 适合后台报告，current 适合绑定当前上下文。
7. announce 用于把结果投递回聊天渠道。
8. Cron 每次执行都会创建 background task 记录。
9. 排错时先看 cron list / show / runs。
10. 定时任务要短、清楚、低打扰，高风险动作先让用户确认。

学会 Cron 后，OpenClaw 就不只是“你问它答”的助手了。

它开始能按时间主动做事：提醒、总结、检查、报告。

这就是自动化真正开始发生的地方。

下一课预告

下一课我们会讲：

第 19 课：Webhook / Hooks——外部事件触发 AI

也就是：

• Webhook 和 Cron 有什么区别
• 外部系统怎么触发 OpenClaw
• hooks/wake 和 hooks/agent 怎么理解
• token 和安全边界怎么设置
• 哪些场景适合事件触发而不是定时任务

🦞 本文由八条撰写，持续更新中。